Documentation for Users  1.0.1
Perception Toolbox for Virtual Reality (PTVR) Manual
Overview of PTVR

Main characteristics

PTVR is a free and open-source library for creating visual perception experiments in virtual reality using Python (the PTVR Backend is Unity but knowledge in Unity is not necessary).

The PTVR library's ambition is to let you design and implement visual perception experiments in virtual reality using high-level Python script programming. It is intended to help researchers in behavioral sciences leverage the power of virtual reality for their research without the need to learn how virtual reality programming works.

The philosophy of PTVR is thus very close to the approach of PsychoPy ( that has been so important and influential since 2007 for Vision Science researchers displaying stimuli on 2D monitors.

Some assets of PTVR

  • VR experiments can be created rapidly and succinctly by researchers thanks to clearly structured high-level python scripts.
  • The use of such scripts, along with the transparency of the PTVR open-source code, is one of the necessary components to address the 'reproducibility crisis' in science and foster Open Science.
  • Researchers can learn PTVR quite quickly thanks to two main resources:
    • A rich online documentation provided with many animated figures in 3D to help visualize some 3D subtleties (will be released soon).
    • Many "demo" scripts (included in the PTVR library) with didactic 3D and/or interactive features.
  • The terminology used in the PTVR code is familiar to vision scientist. For instance, researchers can use an intuitive "Perimetric" coordinate system allowing them to easily place their 3D stimuli with eccentricity and half-meridian coordinates.
  • Intuitive ways of dealing with visual angles in 3D.
  • Intuitive ways of dealing with the notorious difficulty of rotating 3D objects.
  • An implementation of "flat screens" to replicate and extend standard experiments made on 2D screens of monitors.
  • Easy ways of recording experimental results.
  • Easy Gaze tracking and recording.
  • Easy Head tracking and recording.
  • Focus on the implementation of standard and innovative clinical tools for visuo-motor testing and visuo-motor readaptation (notably for low vision).
  • Great care to create accurately controlled text stimuli in the spirit of the psychophysics of Reading.


  • An HTC Vive Pro Series VR system (headset, hand controllers, ...) (
  • A Windows computer with HTC Vive already set-up. See HTC Vive setup for help with this.
  • Python >3.6. We suggest Anaconda, a nice Python distribution, and Spyder, a nice integrated development environment (IDE) already included in Anaconda.

Future PTVR versions will support other VR systems.


  • PTVR is built using the Unity game engine (you will however not have to install Unity yourself).
  • The PTVR project folder can easily be opened as a Unity project (you will however not have to install Unity yourself).

Attributions of images

Image from Notas de prensa, CC BY-SA 2.5, via Wikimedia Commons.